\section{Compilation Units}

\begin{quote}

\ntermdef{CompilationUnit}

\defspace \keyw{package} \nterm{QualifiedIdentifier} \code{;} \nterm{Decls}

\end{quote}

A compilation unit is made up of a (required) package clause followed
by a sequence of declarations.

\pII{
\subsection{New Import Design (overrides below)}
%
Goals
 * modules should be parametric in their imports by default
%
 * programming in an extensible world should look like, and be no more
 costly than, programming in the Java style (packages and imports)
%
 * if you have security constraints and don't want things to be overridden,
there should be a (not too painful) way to enforce that
%
the import statement looks like Java, but means requires a module with
the right signature.
%
by default, an import gets resolved to the actual implementation module
named.
%
there is a mechanism for redirecting the import to some other module
that conforms to the signature (this is done in a surrounding module
or some kind of package mechanism)
%
there is a mechanism for sealing imports (really just binding them to
their defaults) to a module or to a package so they cannot be rebound
externally.
}
\subsection{Imports}

\begin{quote}

\ntermdef{Decl}

\defspace \keyw{import} \nterm{QualifiedIdentifier} \opt{\nterm{DotStar}} \code{;}

\ntermdef{DotStar}

\defspace \code{. *}

\end{quote}

An import statement imports a qualified name into the current scope so
it can be referred to by the last identifier in the qualified name.
If the import ends in .*, then all the members of the given
\nterm{Name} are imported into the current scope.  When a name from a
wildcard import is used, the compiler must be able to find the actual
declarations in that scope in order to properly resolve them; if the
declarations are unavailable, each declaration used must be imported
separately.  Any top-level external identifier used in the file must
be declared as an import, except for the identifier ``plaid'' for the
Plaid standard libraries; this preserves the property that the
compiler always knows what top-level identifiers are legal to access.

As in Java, importing the same simple name twice is an error unless
the fully qualified name is the same.  Importing a specific simple
name always overrides importing all elements of a package where
that name is defined, regardless of which definition goes first.
In general, Plaid follows the Java Language Specification section
7.5.

\TODO{Need to define imports more precisely!  look at Java.  Address
conflicts between local names and imports.}

\subsection{Copmilation Unit Semantics}

We define the semantics of a compilation unit in terms of ordinary
Plaid objects.  Each compilation unit is semantically an immutable
object with an ``instantiate()'' method that can be used to
instantiate a fresh module object.

Freshly generated module objects have methods defined for each of the
top-level method declarations in the compilation unit; however, top
level field declarations from the module are still missing.  They also
have abstract fields for the top levels of imported modules, which are
given the types declared in the source code~\footnote{There is no
  syntax for this yet}.  If no type for the import is given, the
compiler looks up the imported module according to its current
configuration\footnote{When targetting Java this is typically done
  with the PLAIDPATH, as defined below} and uses the type of the
module found for this import.  Note that even though the type of a
module found by the compiler may be used, the actual import is not
bound until the module is linked.

\cut{
It has a concrete field for the top level of the package being
created, and so forth with concrete fields going up to an object
representing the file.  In that object, imported names are replaced
with fully-qualified names.
%
The module object must be immutable; when instantiated, it executes no
code and allocates no storage (nor has storage allocated for it).
%
QUESTION: is this realistic?  Would it help if everyone had implicit
access to a ``system'' object?  Would it help if we made exceptions
only for state that is innocuous, e.g. caching, logging, or unique
token generation?
}

Code within the module object may refer to imported modules.  These
references are references to the abstract fields provided by the
imports.  In the case of an import m.* declaration, m is imported and
all names in the module that were found in m.* have an ``m''
prepended.

A module is linked to other modules by using the m <- { p = p\_def }
syntax, where p is the name of the imported module and p\_def is the
definition of the imported module, as specified at link time.  Linking
typically occurs whenever a module is first loaded into the run-time
system.

A fully-linked module object contains a special method
``initializeModule()'' which creates the proper fields and invokes
their initialization code.  At this point, the methods defined in the
module object can be invoked and the fields defined can be accessed.


\subsection{Module Composition and Hierarchy}

Two or more module objects may be composed using Plaid's \keyw{with}
operation to form a single module that has a union of the declarations
from each constituent module.  Plaid's composition semantics will
naturally merge imports with the same name from the two module
objects, but renaming can be used to distinguish them if desired.  The
module objects' \code{initializeModule} methods will conflict, so
these must be renamed and a new \code{initializeModule} method must be
defined, which should call the previous \code{initializeModule}
methods in order to properly initialize the constituent modules.

Modules may also be combined into a higher-level module, forming a
module hierarchy.  In this case, the higher-level module should be
created by calling plaid.system.modules.newModule(), and then the <-
operator should be used to add fields to the new module that refer to
each of the constituent modules.  Required fields should be defined
for imports of the higher-level module, and imports of the constituent
modules should be either linked to each other or should refer
\TODO{lazily} to the imports of the higher-level module.  The
\code{initializeModule} function should once again be defined to
properly initialize each of the constituent modules.

\TODO{actually, lets say they're initialized lazily.  How does the
runtime support this?  Do we check for bottom due to recursion?
does it help with code loading?}

Once a module has been linked or combined with another module, a new
package representing the combination may be formed by calling the
\code{asPackage} method.  This method returns a new package object,
such that calling ``instantiate()'' will generate fresh copies of the
module and everything it was linked with.  The method used to create
the package is passed the fully qualified name the package is to have.

Package objects support code generation appropriate to the platform,
allowing them to be written as binary code (or bytecode) in the file
system and loaded later.  \TODO{define the interface for this}


\TODO{define a convenient declarative linking system, in a tool spec}

\TODO{later, consider versioning, etc.}

\subsection{Package Loading}

Programmers can load package objects from within Plaid using a package
loader, using the code \code{plaid.system.defaultPackageLoader().loadPackage(\textit{$<$package-name$>$})}.
The default package loader looks up the module to be instantiated on
the PLAIDPATH, but other package loaders can\footnote{In the future,
  once we define the appropriate interface} be used to search for
modules in other ways.

\TODO{define the rest of the interface of PackageLoader}



\subsection{Applications}

An application is any globally-visible method that takes no arguments
and is declared at the top level of a package.

\noindent
The user can start an application using the following command line
syntax:

\begin{quote}
\cmdline{plaid packagename.functionname}
\end{quote}

\noindent
where \cmdline{packagename} is a potentially qualified name.  The
Plaid runtime will look up the package referred to by the packagename
and load it.  The package will be instantiated and its imports will be
linked with modules that are looked up and instantiated in the same
way.  Then \code{initializeModule} will be invoked, followed by the
top-level function the user specified.  The Plaid runtime can also be
invoked with simply the name of a package, in which case the package's
\code{main} function will be invoked.

\subsection{File System Conventions}

A compilation unit is stored in a file with extension .plaid.
The file
must be stored in a directory that can be found using the PLAIDPATH
mechanism described below.

% For example, all $x_1$.$x_2$ package must be stored in
%\$CLASSPATH\$/$x_1$/$x_2$/.

Each compilation unit may have one top-level declaration that has the
same name as the file name (without the .plaid extension).  This
declaration is the only one that is visible from other files. All
other declarations in the file are local.

Other public declarations may be placed in a special file named
package.plaid. There may be one package.plaid file per package. All
declarations in this file are public.

\TODO{later: all decls are private except those specified as public.
  even later: integrate with a mechanism supporting signature
  ascription}


The Plaid compiler and runtime look up packages using the PLAIDPATH
mechanism.  The PLAIDPATH is a path specified in the same way as a
CLASSPATH in Java.  In particular, it is a sequence of files or
directory names separated with a system-specific file separator
character, which is ':' in unix and ';' in Windows.  When looking up a
qualified name, the PLAIDPATH is searched in order first of prefixes
of the name, and next in the order of files in the PLAIDPATH, for
matching .plaid files or binary or bytecode files.  If a Plaid file is
found with no corresponding binary or bytecode file, the Plaid file is
dynamically compiled.

\cut{
Plaid uses the Java classpath mechanism to find files.  When searching
for a definition for a qualified name $x_1$.$x_2 \ldots x_n$, where $x_1$ is not in
scope, the system will search for a directory under the classpath
named $x_1$ and then look for a file named $x_2$ there.  If the file is a
directory, the search proceeds with $x_3$ and so forth.
%
For each top-level declaration in the file, a Java class in the package declared
is created with the name of the top-level declaration.  The Java class
implementing a declaration is found at run time using Java's normal
classpath-based lookup mechanism.
}





\section{Java Language Binding}

This section defines the Java language binding to Plaid, specifing
how Plaid and Java code can interoperate.


\minisec{Accessing Java from Plaid.}  Any java package, class, or
class member can be referred to via a qualified name.  Imported
name(s) can include a package, class, or class member from Java.
Instances of a Java class C may be created by invoking C.new(...)  and
passing appropriate arguments for one of the constructors of class C.
A static method m of C may be invoked with the syntax C.m(...).  An
instance methods of a Java object o may be invoked with the syntax
o.m(...).  Arguments passed to calls of Java constructors and methods
may be Java objects.  Plaid integers, strings, and booleans are
converted to appropriate Java primitive, String, and numeric object
types (e.g. java.lang.Integer) depending on the declared type of the
method's formal parameters.  If a Java method takes an Object or
plaid.runtime.PlaidObject as an argument, then a Plaid object can be
passed to it, allowing Java code to access Plaid objects.

\minisec{Implementing Java Interfaces.}  When a Plaid object is first
created, or a state is defined, the \keyw{with} operator can be used
to compose a Java interface.  In that case, any \keyw{new}
expression that creates an object with that state will generate a
Plaid object that extends the appropriate Java interface.  The Plaid
object may then be passed to a Java method that takes the interface
type as an argument.  Methods of the interface that are invoked by
Java are converted into calls to Plaid methods of the same name and
arguments, as described immediately below.

\minisec{Accessing Plaid from Java.}  Java code may invoke methods of
Plaid objects when those objects implement Java interfaces, as
decribed above, or reflectively through the plaid.runtime.PlaidObject
interface.  When calling a Plaid method through this interface, Java
objects of type Integer, String, Booleans, and other numeric objects
are converted into the corresponding Plaid types.  PlaidObjects and
Java objects are passed through unchanged, and their methods may be
invoked from Plaid in the usual way described above.  The detailed
interface of plaid.runtime.PlaidObject is specified in the javadoc
for that interface.

The Plaid object representing a given Plaid package is accessible in
Java via the static method packagename.getPackage().  Note that this
only works for a top-level Plaid package; the package must have its
imports resolved before sub-modules can be extracted from the package.

As a convenience, a Java function corresponding to each top-level
function is created, which starts the Plaid runtime and executes the
function as if the \cmdline{plaid} command-line utility had been used.
Thus Plaid programs can be invoked exactly like Java programs using
the java command line tool, as long as the Plaid program files and the
Plaid runtime jar file is in the CLASSPATH.


\TODO{how are packages packed into jar files?}

\TODO{Clean interoperability between the null value in Java and
the Plaid type system}

\TODO{Do we want PLAIDPATH to be different from the Java CLASSPATH?
  Maybe the CLASSPATH is used if PLAIDPATH is not defined?}







\pII{
\subsection{IDE considerations}
%
IDEs should show state changes where they occur in code.  For example:
%
\begin{quote}
\code{file.close()       file>>ClosedFile}
\end{quote}
}
